home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection 1998 Fall: Game Toolkit / Disc.iso / SDKs / PCI Driver Development Kit / • Tools / Utility / LogLibrary 950622 / !Log ReadMe next >
Encoding:
Text File  |  1996-08-20  |  5.0 KB  |  116 lines  |  [TEXT/ttxt]
  1. Display Log Library
  2. Copyright © 1992-93, Apple Computer Inc. All Rights Reserved.
  3.  
  4. Quick Reference Manual
  5. • Copy the LogLibrary shared library to the Extensions folder
  6. •  Add the dcmd (in the DisplayLog file) to the MacsBug Debugger
  7.     Prefs file.
  8. •  Include LogLibrary.h in all applications/drivers/whatever that
  9.     use the library.
  10. •  Include LogLibrary.c in all 68000 modules.
  11. • Include the time conversion, time formatting, and data formatting
  12.     functions in display applications.
  13. • See LogLibrary.h for function definitions.
  14.  
  15. Edit History
  16. 93.11.06 MM  Call StripAddress on the "high memory" location
  17.         to prevent bogus string rejection.
  18. 93.12.06 MM
  19.         • Edited Audit so it is a library of modules, rather
  20.         than a single monolithic function. This gives a smaller
  21.         memory footprint for drivers (etc.).
  22.         • Bug: DisplayAudit never disposed of ancient strings
  23.         and, consequently, would crash after about 6 hours.
  24.         • After fixing the bug, I replaced LogManager by LogPane
  25.         (roughly same functionality, but less handle thrashing).
  26. 94.07.18 MM
  27.         • Now compiles for Power PC and 68000 using MPW,
  28.         Think C 7.0 (68000), and MetroWerks 1.0 (68000 and
  29.         Power PC). MPW builds a fat application.
  30.         • Removed the 68000-specific interrupt disable code,
  31.         replacing it by a simple semaphore. This permits the
  32.         code to work in a fully native PPC environment. However,
  33.         it also brings with it a extremely low risk of data loss that
  34.         can only happen if multiple asynchronous processes attempt
  35.         to log data at the same time. I judged that the advantage
  36.         of working comfortably in a native environment outweighed
  37.         the potential data loss.
  38.         • Power PC (native) does not support the stack trace format
  39.         operation.
  40.         • The Build Audit AppleScript builds Think and MetroWerks
  41.         versions. It is still a bit rough around the edges.
  42. 94.12.12 MM
  43.         • Rewritten for PCI Power PC as a native application that
  44.         uses the Driver Services and Name Registry capabilities.
  45.         The driver library does not use the Macintosh Toolbox;
  46.         this allows logging from new regime device drivers. The
  47.         library is now called "DriverLog" The functions are
  48.         generally compatible with Audit, but not totally so.
  49. 95.01.22 MM
  50.         • Debugged and got mostly working as a shared library, fat app, and
  51.         MacsBug dcmd. Known bugs:
  52.         • Timing is incorrect. I'm pretty sure I know how to fix it, but this
  53.         will require rebuilding the library and there are more pressing
  54.         problems right now.
  55.         • The dcmd has a few minor "off-by-one" errors.    
  56.  
  57. DisplayLog is a small library of functions that provide an unobtrusive
  58. event tracing capability to applications, drivers, code-resources,
  59. call-backs, and any other "flavor" of Macintosh software.
  60.  
  61. The initialization function (MakeLogRecord) must be called from a
  62. "memory-safe" environment (i.e., MakeLogRecord may not be called from
  63. a driver interrupt routine), but all other functions may be called
  64. at any time.
  65.  
  66. The MakeLogRecord functions are defined by comments in LogLibrary.h and
  67. LogLibrary.c A Microsoft Word 5.0 document, “About Log” documents the program.
  68.  
  69. The Display  Log application may be used to follow the execution
  70. of a program being audited.  It can display auditing from several
  71. sources, and allows logging the audited data to a text file.
  72.  
  73. The LogLibrary requires the following system facilities:
  74.  
  75. • Driver Services Library
  76. • Name Registry Library
  77.  
  78. The following are provided:
  79.  
  80. • LogLibrary.h -- this header file must be included by all functions
  81.   that use the DriverLog. It defines library structures and functions.
  82. • LogLibrary.c -- this file contains the C functions that support
  83.   debugging. It is linked into all 68000 modules that need this support.
  84.   (Linkage is needed to provide Mixed Mode glue). It is also provided as
  85.   a shared library.
  86. • LogFormat.c contains a function to format driver log entries.
  87.   It does not use the Macintosh toolbox. It is not in the shared library.
  88. • LogFormatTimestamp.c and LogConvertTimestamp.c provide functions
  89.   to convert the timestamp provided in all log entries from "UpTime"
  90.   format to civil time. A Macintosh Toolbox function is needed to form
  91.   the DateTimeRec, hence these functions are not in the library.
  92. • MakeFile -- this MPW MakeFile builds the DriverLog DCMD and the
  93.   DisplayDriverLog application.
  94. • LogDCMDSrc -- this folder contains a copy of the MacsBug dcmd support
  95.    functions.
  96.  
  97. Building:
  98.  
  99. 1. Use the Makefile to build DisplayLog (this builds everything you need).
  100. 2. For MetroWerks, use the Makefile to build the MetroWerks resources,
  101.     then use build the DisplayLog.µ 68000 application and, finally, the
  102.     DisplayLog.Δ fat binary. Building a fat binary is overkill, but was useful
  103.     in testing the application.
  104. 3. If you wish, use the DisplayLog.π project to build a Think C 68000
  105.     variant (again, for testing).
  106. 4. Use Resedit to copy the 'dcmd' 20000 resource to the Debugger Prefs
  107.     file (in the System File) and copy the LogLibrary shared library to
  108.     the Extensions folder.
  109.  
  110. Limitations and known bugs
  111.  
  112. • Only MPW can build the dcmd.
  113. • Fractional seconds appear incorrect.
  114.  
  115.  
  116.